.TH std::allocator::deallocate 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::allocator::deallocate \- std::allocator::deallocate

.SH Synopsis
   void deallocate( T* p, std::size_t n );  (constexpr since C++20)

   Deallocates the storage referenced by the pointer p, which must be a pointer
   obtained by an earlier call to allocate()
   or allocate_at_least()
   (since C++23).

   The argument n must be equal to the first argument of the call to allocate() that
   originally produced p
   , or in the range [m, count] if p is obtained from a call to allocate_at_least(m)
   which returned {p, count}
   (since C++23); otherwise, the behavior is undefined.

   Calls ::operator delete(void*)
   or ::operator delete(void*, std::align_val_t)
   \fI(since C++17)\fP, but it is unspecified when and how it is called.

   In evaluation of a constant expression, this function must deallocate  \fI(since C++20)\fP
   storage allocated within the evaluation of the same expression.

.SH Parameters

       pointer obtained from allocate()
   p - or allocate_at_least()
       (since C++23)
       number of objects earlier passed to allocate()
   n - , or a number between requested and actually allocated number of objects via
       allocate_at_least() (may be equal to either bound)
       (since C++23)

.SH Return value

   \fI(none)\fP

.SH Example


// Run this code

 #include <algorithm>
 #include <cstddef>
 #include <iostream>
 #include <memory>
 #include <string>

 class S
 {
     inline static int n{1};
     int m{};
     void pre() const { std::cout << "#" << m << std::string(m, ' '); }
 public:
     S(int x) : m{n++} { pre(); std::cout << "S::S(" << x << ");\\n"; }
     ~S() { pre(); std::cout << "S::~S();\\n"; }
     void id() const { pre(); std::cout << "S::id();\\n"; }
 };

 int main()
 {
     constexpr std::size_t n{4};
     std::allocator<S> allocator;
     try
     {
         S* s = allocator.allocate(n); // may throw
         for (std::size_t i{}; i != n; ++i)
         {
         //  allocator.construct(&s[i], i + 42); // removed in C++20
             std::construct_at(&s[i], i + 42);   // since C++20
         }
         std::for_each_n(s, n, [](const auto& e) { e.id(); });
         std::destroy_n(s, n);
         allocator.deallocate(s, n);
     }
     catch (std::bad_array_new_length const& ex) { std::cout << ex.what() << '\\n'; }
     catch (std::bad_alloc const& ex) { std::cout << ex.what() << '\\n'; }
 }

.SH Output:

 #1 S::S\fB(42)\fP;
 #2  S::S(43);
 #3   S::S(44);
 #4    S::S(45);
 #1 S::id();
 #2  S::id();
 #3   S::id();
 #4    S::id();
 #1 S::~S();
 #2  S::~S();
 #3   S::~S();
 #4    S::~S();

.SH See also

   allocate          allocates uninitialized storage
                     \fI(public member function)\fP
   allocate_at_least allocates uninitialized storage at least as large as requested
   (C++23)           size
                     \fI(public member function)\fP
   deallocate        deallocates storage using the allocator
   \fB[static]\fP          \fI(public static member function of std::allocator_traits<Alloc>)\fP

